BBS Toolkit

home *** CD-ROM | disk | FTP | other *** search

/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rbbsdocs.zip / RBBSDOCS.12A < prev next >

Wrap

Text File | 1990-11-05 | 31KB | 577 lines

RBBS-PC's FILE MANAGEMENT SUBSYSTEM 12-1 12. RBBS-PC's FILE MANAGEMENT SUBSYSTEM --------------------------------------- The File Subsystem allows RBBS-PC to maintain a list of files available for downloading. Users can list files by date, category, or by using a search argument. RBBS-PC refers to a file that contains a list of files available for downloading as a "directory" (i.e. a .DIR file). This should not be confused with DOS "subdirectories." There are two ways to configure the File System. One is to have simple "directory" files. The other is to have a FILE MANAGEMENT SYSTEM (FMS) file that contains the names, sizes, dates, and description of all the files available for downloading. You may use both methods at once if you wish. RBBS-PC will support both a master FMS and separate .DIR files on the same system. CONFIG parameter 215 controls whether RBBS-PC looks beyond the FMS directory. If you have any separate directories, set 215 to NO. If you have only a single FMS directory, set parameter 215 to YES. If directory searches are not limited to the FMS directories and RBBS-PC does not find the category in the FMS listing, it will look for the old-style DIR files. 12.1 Simple Directory Format ---------------------------- The simple directories, also referred to as the old-style directories, are simply text files. These files are identified by their file extension, specified in CONFIG, common to all the directories. The default extension is .DIR, but it can be changed via parameter 209. There is a directory which lists the directory names and their descriptions whose name is specified via parameter 211 of CONFIG. Each directory may have anything in it, including ANSI codes. The only restriction is that in order for the N)ew command to work properly, the date must be somewhere in the first 31 characters. All uploads are placed into a single directory, called the upload directory, specified in parameter 202 & 203. All other directories must be in the drive\path specified in parameter 220. This includes the FMS directory and the list of DIR files, (DIR.DIR). There are, therefore, four logical areas into which the file subsystem is divided. Each one may reside in a separate DOS subdirectory, or all of them may be lumped together. Logical Area CONFIG 1. The files for DOWNLOAD parameter 204, parameter 205, and parameter 207 2. The files that have been uploaded parameter 201 and parameter 206 3. The upload directory file listing. parameter 202 and parameter 203 4. The download directory files. parameter 220 The file management system not only manages these "lists" of files, but it manages where on your system the files are actually stored. RBBS-PC will not allow a caller to download a file unless it finds this file where the SysOp has instructed RBBS-PC to look. There are two ways of doing this: A download "path," and the Fast File Search. Config parameter 204 tells RBBS-PC which DRIVES can be checked for downloads. If you do not use DOS subdirectories, RBBS-PC looks on these drives for downloads. The parameter is specified with the drive letters to RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 12-2 search. For example: BAC would search Drive B, then Drive A, then Drive C. If the files are not in the default directory then you need to use the CONFIG parameter 205 and parameter 207. Parameter 205 specifies that you want to sue DOS sub-directories and parameter 207 allows you to list them. Use drive:\path format. Any directory can be in the Single FMS format. This allows special purpose directories to be put into FMS format so they can take advantage of such features as resumable listings normally associated just with the Single FMS environment. An unlimited number of lines of text can be added to any description (see CONFIG parameter 40, parameter 148, and parameter 153). The file directories have absolutely no bearing on what is in the subdirectory. A file can be listed but not exist, and a file, such as one uploaded with the / for SysOp option, may exist but not be entered. The file directories are simply methods to get the caller a listing of the files available. 12.2 The Single and Chained FMS Directory Format ------------------------------------------------ FMS logically just lumps all the old style separate directories into one directory file, called the MASTER or FMS directory, and assigning each file a CATEGORY CODE, which may correspond to the directory it was in the original directories. A utility program called CNVDIR.EXE will do exactly this: combine the separate directories and add the category code at the end. If you do not already have separate directories, simply set it up with a text editor using the columns indicated. Beginning with 17.2A FMS directories can be "chained". This means that physically separate files can be logically combined to form a single FMS directory. This is accomplished by putting the following in the header record (a header record in an FMS directory is the first record and must begin with "\FMS "): CH(<chain to>) where <chain to> is the name of the file to chain to. As an example \FMS CH(C:\DIRS\CHTO.DIR) would chain to the file "C:\DIRS\CHTO.DIR". Names of files not in the default directory must have a drive and/or path specified. The directory chained to can in turn have a chain, and there is no limit to the number that can be chained together. Note that this "header" record must have the same length as the rest of the lines in the directory, and will usually have to be padded out with blanks. The directory chained to is an independent FMS directory and can be anywhere and have any extension. A given directory can have at most one directory to chain to. Chained directories can be used to keep the upload directory small for easier editing, or to better fit the latest directories on a fast RAM disk while keeping older directories on a slower hard disk (e.g. a SysOp divides the directories into UPLOADS.DIR, 87.DIR, 86.DIR, 85.DIR, and 84.DIR to reflect the year in which the file was created/uploaded). RBBS-PC's FILE MANAGEMENT SUBSYSTEM 12-3 12.3 Advantages/Disadvantages of FMS Directory ---------------------------------------------- Having a FMS directory has the following advantages: 1. Callers get the newest files listed first. The directory can be displayed EITHER from top to bottom or bottom to top. Reading from bottom up is appropriate when files are in date order and new files are appended to the bottom. When files are alphabetized or grouped some other way, it is more appropriate to read them from the top down. 2. The directory is listed with MORE ([Y],N) or files to download prompts throughout the listing, so at any time the caller may begin downloading, and pick up where they left off in the listing after the download is completed. 3. Wildcard searches on filenames are supported as well as exact matches on strings in the file S)earch command. Whenever a wild card character (* and ?) is specified in the search string, RBBS-PC will automatically shift to matching just the file name. Exact string matches search the full entry rather than just the file name. String searches include extended descriptions for FMS directories, but in non-FMS directories only the first line of the file description is searched. 4. Classification of files is easy. All that is necessary is an editor that produces ASCII files, and a file is classified by a category code of up to 3 characters. To change a file from directory to directory, all that is necessary is to change the category code. No more "erase it here and add it there." 5. No SysOp maintenance is necessary for new uploads. The caller can classify the upload with a category code, and the SysOp can specify that the new uploads become instantly available. 6. Complex classifications can be made very simply. A category code is not necessarily the category the caller must type in. The SysOp can elect to have a classification system where one code that the caller types in will list several different category codes. You can include the file in two directories without having two separate entries. 7. FMS directories can have "headers" (i.e. free text lines not associated with any particular file). This allows things like column headers or help to be included, as well as section headers. A SysOp may wish to separate a "communications directory" into different sections such as one for QMODEM and one for RBBS-PC. A free text line begins with "*" and is universally displayed if the category code is "***" otherwise it is only displayed when the category associated with the line is selected. 8. Multi-line descriptions (i.e. "extended" descriptions) are supported in both FMS and "old-style" directories. All columns except the first one are available for the description. For FMS directories extended descriptions have the same characteristics as the file that they are associated with. 9. The ability to enter "extended" descriptions for uploaded files is based on the caller's security level (see CONFIG parameter 127). RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 12-4 10. Caller's can list the RBBS-PC file directories with or without extended description. As an example, a caller would enter the command "L - UPLOADS" to list the files in the directory UPLOADS with only one line descriptions. The command "L + UPLOADS" would list the same file with extended descriptions. 11. Archived files can be viewed with the V)iew command when listing FMS directories and the listing will resume where it left off prior to issuing the V)iew command. 12. Individual entries within a FMS directory can be restricted to specific security levels. 13. Comment lines can be included in FMS directories which are never shown to a caller. Often such comments are useful reminders to the SysOp who is maintaining the FMS directories. 14. Callers can add upload descriptions without actually uploading a file (see CONFIG parameter 153). This is typically useful to the SysOp. It makes it easy to start an FMS upload directory without having to know anything about its internals or how to use an editor. With the exception of a CORVUS network environment, FMS directories can be updated without taking the system down first. All the caller does is issue the normal upload command. If RBBS-PC finds that the file already exists and that the caller has the necessary security level, RBBS-PC will get the file size and proceed exactly as if the file had just been uploaded. 15. Searches for new files is EXTREMELY fast because RBBS-PC does not have to search all directories if the single FMS directory is in date order (most recent date last) 16. Latest uploads are always shown first, if the SysOp has elected to make them viewable and the master FMS is in date order. 17. Searches for text will scan the text in the extended multi-line descriptions. 18. Composite categories can be logically constructed out of other categories (see section 12.5). 19. Entries do not have to be physically moved to other .DIR files to be classified as belonging to it. 20. FMS directories can be "chained" to accommodate those multi-user environments, such as Corvus's OMNINET, which will not allow files that change in length to be shared. In such an environment FMS can be used, but the FMS directory must "chain" to the upload directory and their must be a separate upload directory for each node. Regrettably, the FMS directory also has ONE remaining limitations which may make it unsuitable for all SysOp's needs. 1. The date must be in MM-DD-YY format. Any single digit number must have a leading zero. If FMS does not totally satisfy your needs, you can use both. RBBS-PC can be configured to look for an old style directory if it does not find a RBBS-PC's FILE MANAGEMENT SUBSYSTEM 12-5 directory in the FMS. If it finds one it will display it. If it does not, it displays the familiar "Directory XXX not found!" message. 12.4 Creating FMS Directories ----------------------------- If you already have separate directories, it would be a good idea to copy all of them into a single one called MASTER.DIR. Detailed directions are given in the documentation for CNVDIR. In DOS this can be done like this: COPY xxx.DIR+xxx.DIR+xxx.DIR... MASTER.DIR where xxx is the name of the old style directories. The 3 dots mean to continue until you have all of the directories you wish to include in the FMS directory. In addition to the "old style" file directories described in section 12.1, RBBS-PC supports two types of FMS "directories" -- multiple, single-subject FMS directories or a single multiple-subject master FMS directory. If there are going to be multiple, single-subject FMS directories, there must also be a "directory of directories" (i.e. a master directory) whose name is specified in CONFIG parameter 211 and there can not be more than 99 of these single-subject FMS directories. If there is going to be a single FMS directory, it's name is specified in CONFIG parameter 214 and it's qualifier is specified in CONFIG parameter 209. An example of multiple FMS directories that assumes the following: CONFIG parameter 220 is "C:\FMS", CONFIG parameter 209 is "DIR", CONFIG parameter 211 is "DIR", and the following files existed: C:\FMS\DIR.DIR C:\FMS\ALPHA.DIR C:\FMS\BEST.DIR The file ALPHA.DIR can be a FMS directory with an alphabetical list of all files and BEST.DIR can be a FMS directory with a date-ordered (latest date last) list of the "best" files. An FMS directory can have an optional "header" line that describes the structure of the directory. RBBS-PC searches FMS directories from bottom to top by default (i.e. the assumption is that they are sorted by date with the newest entry at the bottom). To make an FMS directory read from top to bottom, the directory must have the optional "header" line as the first line. For FMS to read a FMS directory from top to bottom the first four characters in the first line must be "\FMS" and the line must contained the three characters "TOP" (i.e. the whole fixed-length line would read "\FMS TOP"). For FMS directories not sorted by date, the word "NOSORT" must be present in the first line (i.e. the whole line would read "\FMS TOP NOSORT"). The file ALPHA.DIR would have the first line in the file read "\FMS TOP NOSORT". The file BEST.DIR would have the first line in the file read "\FMS TOP" if all searches of the file were to start with the oldest (i.e. first) entry. It is important to realize that FMS directories must have a fixed length in every line. The columns of all FMS directories are set up as: Column Purpose 1-13 Filename 14-22 File size RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 12-6 24-31 Date in MM-DD-YY format 34+ Description + category code To add comments to an FMS directory and not have them shown to the caller, simply begin the comment line with a slash, "\". To force a line to be displayed that is not associated with an FMS directory entry, begin the line with an asterisk and, if it is displayed for only specific categories, the appropriate category restriction. To make an FMS entry visible only to callers with a specific security level or higher, the first character of the file name must be an equal sign, "=". For this entry, the file name is in columns 2 through 13. The minimum security to view this entry goes in column 34 and is followed by a blank and then the description and category code within the columns appropriate for them (based on CONFIG parameter 219). CONFIG parameter 219 specifies the length of the "description" field (40 to 46). The column containing the "category" codes can be variable as follows: Length Columns for description Category code column 40 34-73 74-76 41 34-74 75-77 42 34-75 76-78 43 34-76 77-79 44 34-77 78-80 45 34-78 79-81 46 34-79 80-82 However, some text editors may have a problem with lines 80 or more columns. The fussiest areas for use with FMS are the DATE and CATEGORY CODE fields. These two must be absolutely perfect for FMS to function properly. The others may be slightly more lenient. In order to get the directory in the correct format, insert and delete spaces before and after the column. The file name should not have interior or leading blanks. You must also add a category code to each listing. This is often the most difficult and time consuming part of setting up FMS. A good idea is to format the rest of the directory before you add the codes. CONFIG has a utility, parameter 187, that will check your FMS directory structure for you. If a caller uploads with a "/" for SysOp, a *** is placed for the category code and only those with a SysOp security level may view the listing (see CONFIG parameter 125). 12.5 Defining the FMS Category Codes ------------------------------------ In order for FMS to work correctly, the category codes must be defined. This is done in a file specified in parameter 217 of CONFIG. This file is rather interesting in the way it is set up and the possibilities it brings up. The format of this file is, with each line being a separate entry: "<Category name>","<Category codes>","<Category description>" RBBS-PC's FILE MANAGEMENT SUBSYSTEM 12-7 The category name is what the caller types in L;xxxxxxxxxx. The category codes are a list of the character codes in the FMS directory that we want to be under this category name. Category codes can be 1 to 3 characters long, though the simplest and most foolproof method is to make them all exactly 3 characters long. The category description is a short messages that we want displayed when the category is searched for. If the category codes are less than 3 characters in length, blanks must be added to the right to fill out the length to exactly 3 when putting the category codes on the end of file entry. A listing can contain several category codes. This means that a category name of BASIC could have the category codes BSU,BSG,BSS in it. The category codes may be overlapped in several different directories. For example, the BASIC directory used as an example could also have each code included in another directory. UTILS could contain DSU,PRU (Dos utils, Printer utils). GAMES could contain CGG,BSG,TXG (Color Graphics Games, Basic Games, Text games). BASIC could contain BSG,BSS ( Basic Games, Basic Source). SOURCE could contain ACS,BSS (Assembly code source, Basic Source) Such a setup would look like this: "BASICG","BSG","Basic Games" "TEXTG","TXG","Text Games" "COLORG","CGG","Color Graphics Games" "PRINT","PRU","Printer Utilities" "DOS","DSU","Dos Utilities" "ASSEM","ACS","Assembler source code" "BSOURCE","BSS","Basic Source Code" "UTILS","DSU,PRU","Utilities for IBM" "GAMES","CGG,BSG,TXG","Games for IBM" "BASIC","BSG,BSS","BASIC programs" "SOURCE","ACS,BSS","Source code for different languages" The directory might look like: FFIND.ARC 13463 05-24-87 DOS Util look all over disk for file DSU QUEST.ARC 17325 06-02-87 C/G Game D&D style CGG RBBS-SRC.ARC 202562 06-05-87 Source code for RBBS-PC BSS QMODEMSC.ARC 106735 06-07-87 Source code for QMODEM SST PSS BALLOON.ARC 5634 06-08-87 BASIC Balloon game- GREAT BSG STARTREK.ARC 76434 06-10-87 A great game- TEXT TXG When someone lists out GAMES, they get QUEST, BALLOON, and STARTREK. You can also have simply a one to one correspondence, rather than cross referencing by just having one category code for each category. A utility that will help you in setting up your FMS directory is a SysOp function built into CONFIG. Parameter 187 will test the structure of your FMS directory and diagnose any problems. Be sure to run this utility after you have tried to set up FMS, or whenever you edit the FMS directory file. 12.6 The "Library" Subsystem, CD-ROM, and FMS --------------------------------------------- The RBBS-PC "library" sub-system is highly flexible subsystem that utilizes DOS 'disk subdirectories. The "library" subsystem is not limited to any particular medium. Basically, it relies on three files: RBBS-PC 17.3A TECHNICAL REFERENCE MANUAL 12-8 DIR.CDR - This is the Directory of Directories just like DIR.DIR is the Directory of Directories for the normal download area. This file is located on the drive and path designated in CONFIG parameter 302, has a file name equal to the extension designated in parameter 303 , and the extension designated in parameter 303. MASTER.CDR - This is an FMS style directory. Highly recommended to have a size of 46 to allow for placing the DISK/AREA number in the last four positions of description. This file is located on the drive and path designated in CONFIG parameter 302. The following is an example of a master directory file, C:MASTER.CDR, that might be used for the "library" subsystem. DEMO.DTA 9841 01-01-80 PRACTICE FORM 680126 READ.ME 256 01-01-80 INTRODUCTORY TEXT FILE 673102 READ.ME 109 01-01-80 INTRODUCTORY TEXT FILE 671102 DK0680 ARC 10-23-87 FORGE VERSION 2.0 200 DK0673 ARC 10-23-87 FREEWAY ...(Disk 3 of 3) 200 DK0671 ARC 10-23-87 FREEWAY ... (Disk 1 of 3) 200 | | | | | | +- 1->13 | | | | | File Name +- 14->22 | | | | File Size | | | | +- 24->31| | | File Date| | | +- 33->76 | | File Description | | 77->79 -+ | DOS | Directory | Number | | 80->82 -+ Category Code The last four characters of the 46-character file description field are used to indicate the "library" pseudo-disk that the file is in. In this way, when a caller lists files, it is self-evident in the description which DOS subdirectory the caller must change to within the "library" subsystem in order to download the file. RBBS-CDR.DEF - This is the key file to the successful operation of the LIBRARY section. It consists of three fields on each line. "AAAA","BBBBBBBBBBBBBBBBBBBBBB","CCCCCCCCCCCCCCCCCC"cr/lf A - A four position field numbered from 0001 to 9999. This is the DISK/AREA number assigned to a specific group of files. B - This field has no size limit and is a full path to the area excluding the drive: designation. As an example: \1_100\DISK0001 \GAMES\ADVENTUR\DISK1 \A_F\ALPHABET\DISK01\AREA36 C - This field has no length limit but should be kept at RBBS-PC's FILE MANAGEMENT SUBSYSTEM 12-9 around 56 characters to keep from line wrap on the display. It should contain the TITLE of the disk/area. A file containing a description of the library subsystem's category codes must have the name RBBS-CDR.DEF, be in the same DOS subdirectory as the other RBBS-PC ".DEF" files, and look similar: "0671","\601-700\DISK671","FREEWAY Payroll system (Disk 1 of 3)" "0673","\601-700\DISK673","FREEWAY Payroll system (Disk 3 of 3)" "0680","\601-700\DISK680","FORGE VERSION 2.0" The "library" subsystem can be supported without using the FMS. To do this each "directory" would have ".CDR" as it's extension (i.e. GAMES.CDR) -- or whatever extension was designated in CONFIG parameter 303. Typically, the "library" subsystem is used with FMS. When using FMS with the "library" subsystem it is necessary to add categories to the DIR.CAT file. One approach that works well is utilizing categories 1-99 for the normal (i.e. non-library area) downloads and categories 100-200 for the "library" downloads. The basic assumption of RBBS-PC's "library" sub-system is that files are stored in DOS subdirectories on the DOS disk drive specified in CONFIG parameter 301. 12.6.1 How the "Library" Subsystem Works ---------------------------------------- Before it is possible to download from the LIBRARY area it is mandatory that the caller C)hange to the desired library disk. This is accomplished by using the C)hange command from the library menu. RBBS-PC will accept any 1 to 4 digit number (padding the front with zeros to make it a four digit number). RBBS-PC will then search the RBBS-CDR.DEF file (position AAAA only) for an exact match. If no match is found then RBBS-PC indicates that no Library disk has been selected. If a match is found then RBBS-PC will issue a CHDIR command to the drive specified in CONFIG parameter 301 and the path BBBBBBBB that it constructs from the RBBS-CDR.DEF file. RBBS- PC then informs the caller that Disk AAAA CCCCCCCCCCCC has been selected (i.e. "Disk 0680 FORGE VERSION 2.0"). The caller can download individual files from the area selected or A)rchive all the files in the selected area. If the caller decides to A)rchive all the files in the selected area, RBBS-PC will SHELL to the Archive program designated in CONFIG parameter 313 and located in the drive and path designated by parameter 312. RBBS-PC creates an archived file with the name DKAAAA.ZZZ, where AAAA is the disk/area number on the drive and path indicated by CONFIG parameter 304, and ZZZ is the extension, which depends on what archiving program is used. RBBS-PC will then check to see if there are any subdirectories within the selected area. If any exist then RBBS-PC will again Archive the subdirectories and will create ZZZ files with the name DKAAAAa.ZZZ where AAAA is the disk/area number. The designator, "a", is an arbitrary id to differentiate it from the original ZZZ name. If there are more than one subdirectories then the "a" would be replaced by "b", "c", "d", etc. When this is complete the caller is told what files are ready for download. E.g.